home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / mxlibs / dwstk102 / readme < prev    next >
Text File  |  1995-04-19  |  7KB  |  145 lines
  1. This is the readme file for v1.02 of DiamondWare's Sound ToolKit.
  2. README.TXT was finalized on 04/12/95.
  3.  
  4. A product like the Sound ToolKit is a complicated beast.  We can't
  5. overemphasize the importance of reading the documentation.  There
  6. are many caveats and subtle ways to improve the performance of your
  7. application in the docs.  We didn't go to all the effort of writing,
  8. just so everyone wouldn't read anyway.  READ THE MANUAL!  <g>
  9.  
  10. This file is an appendix, and is intended primarily for users who
  11. are already familiar with the documentation.
  12.  
  13. If you have the shareware version, STKMAN.TXT is up to date.  Unless
  14. you're upgrading from v1.00, you won't find anything new in here.
  15. This file tells you what's changed.
  16.  
  17. If you have the registered version, read the printed manual first.
  18. Then read this.  It contains everything added since the book was
  19. printed.
  20.  
  21. Improvements
  22. ------------
  23. The API did not change, and no working code was broken.
  24.  
  25.   o  The STK now allows re-entrancy.
  26.   o  dws_DetectHardWare checks the BLASTER environment variable.
  27.   o  The bass drum is louder, deeper, and punchier.
  28.   o  The STK checks the interrupt flag before some STK functions.
  29.   o  We added OPLKBD.EXE (registered version only).
  30.   o  The music playback is now more sensitive to note velocities.
  31.  
  32. You can now call any STK function from any background task,
  33. including an ISR.  If the STK can't deal with the call right then,
  34. it will return a (new) error.  dws_BUSY means that you should call
  35. again later (your next timer tick, or some other soon time).  IF
  36. YOU'RE CALLING THE STK ONLY FROM THE FOREGROUND, THIS ERROR CANNOT
  37. OCCUR.
  38.  
  39. PLAYDWM and PLAYDWD have been updated to show detection of this new
  40. error condition (although neither program can actually generate it).
  41.  
  42. dws_DetectHardWare now uses the BLASTER environment variable to help
  43. it find sound boards.  It looks for the sound board's port at the
  44. address specified in the BLASTER variable.  It will also use the
  45. BLASTER's IRQ and DMA settings as a last resort -- if it's unable to
  46. find them from examining the hardware.
  47.  
  48. When you call dws_DetectHardWare, dws_Init, or dws_Kill, interrupts
  49. must be enabled.  If they're not, you'll get a (new) error.
  50. dws_IRQDISABLED means that IRQs are disabled -- but to work
  51. properly, the STK function you just called requires them to be
  52. _enabled_.  This error shouldn't occur, unless you're developing
  53. interrupt service routines, and other non-mainstream code.
  54.  
  55. For registered users, we added a new program: OPLKBD.EXE.  This
  56. allows you to load an .IBK file, and "play" notes from it on your
  57. 101 keyboard (including polyphony).  It's useful for tweaking .IBK
  58. files.
  59.  
  60. Bugs Fixed
  61. ----------
  62.   o  MID2DWM.EXE no longer requires an FPU.
  63.   o  Some "clickiness" in music playback was eliminated.
  64.   o  SB16 mixer settings now restored properly upon dws_Kill.
  65.   o  Sequencing sounds no longer causes the STK to enter a bad state.
  66.   o  dres.baseport is set even if dws_DetectHardWare can't find IRQ or DMA.
  67.   o  On Windows Sound System, under Windows, dws_DetectHardWare now works.
  68.   o  Inside the STK, interrupts are disabled where necessary.
  69.   o  dws_Kill is slightly quieter.
  70.   o  FM chip reset is more complete.
  71.   o  Obscure change instrument bug fixed.
  72.   o  On OPTI chipset boards (MAD16), mixer and autodetect now works better.
  73.   o  Auto-initialized DMA mode is used whenever supported by the hardware.
  74.  
  75. Because we're using auto-init DMA mode (don't worry if you don't
  76. know what this means -- it's a detail within the STK), dws_DSetRate
  77. makes some noise on some sound boards.  We recommend (though don't
  78. require) that you change rates during periods of silence.
  79.  
  80. Additional Docs
  81. ---------------
  82. We wrote this addendum to address common questions raised by users.
  83.  
  84. The STK music playback engine may behave differently than you'd
  85. expect.  The following is a brief discussion of two bona fide
  86. features which may cause some unexpected problems.
  87.  
  88. The STK is extremely sensitive to velocity.  If you play a song and
  89. the drums or an instrument sound faint (or loud), this is why.
  90. Change the output level of the instrument patch, or use your
  91. sequencer to bring up the volume of the problem track.
  92.  
  93. The STK will allow notes of bells and strings to "ring out" after
  94. they are "key released".  If this is causing undesired effects,
  95. simply make your instrument patches "sustaining".  The STK will shut
  96. such notes down immediately when they are released.
  97.  
  98. Finding the user's sound board is non-trivial, because the user
  99. often doesn't even know what brand he owns, let alone its settings.
  100. So the STK asks the hardware directly.
  101.  
  102. It does a good job, but there are some potential problems.
  103. Sometimes, the STK may be unable to find one or more sound hardware
  104. parameters (almost always the problem lies with finding the DMA
  105. channel).
  106.  
  107. The capability field in the dws_DETECTRESULTS struct will tell you
  108. if the STK found everything it needed for music and for digitized.
  109. If both capability flags are set, then you have nothing further to
  110. do; music and sound will work.
  111.  
  112. However, only the dws_capability_FM flag might be set.  This may be
  113. because the user has music-only hardware, or it may be that (for
  114. example) the STK was unable to find the DMA channel.  To tell the
  115. difference, look at the baseport field of the dws_DETECTRESULTS
  116. struct.  If this field returns as either 65535 or 388h, this means
  117. that no digitized-capable sound hardware is present (or the user's
  118. drivers aren't installed).  If this field returns with any other
  119. value, it means that digitized hardware exists.  Look at the digirq
  120. and digdma fields.  If either or both of these are set to 65535, it
  121. means that the STK couldn't autodetect them (and the BLASTER
  122. environment variable was either not present, or was wrong).
  123.  
  124. Planning ahead for this, you should have a screen where the user can
  125. type in port, DMA, and IRQ channel.  Don't require him to do this,
  126. but make this option available.  Take the settings you are given,
  127. and plug them into the dws_OVERRIDES struct.  Then call
  128. dws_DetectHardWare again.
  129.  
  130. Don't simply look at the capability field of the dws_DETECTRESULTS.
  131. Its boolean flags simply indicate whether or not we figured out
  132. everything we needed to know about music and digitized sound.  It
  133. can't tell you, for example, if we have a port and an IRQ level, but
  134. no DMA channel.  To determine this, look at the baseport, digdma,
  135. and digirq fields.  If baseport is 65535 (or 388h), then we found no
  136. digitized capability.  It's virtually certain that none is present.
  137. If baseport is 220h, digdma is 65535 and digirq is 7, then we
  138. couldn't determine the DMA channel.  Ask the user!  It beats dimming
  139. out your sound option.
  140.  
  141. We provide a new example program to registered users: SETUP.C, which
  142. handles setup of sound settings, and configuration files.  It isn't
  143. pretty (using just printf and scanf), but it illustrates some
  144. important concepts.
  145.